Incidents API: List vs Get

#1

In the Rest API reference, the List Incidents endpoint is described as “List existing incidents”, while Get an Incident is described as “Show detailed information about an incident”.

Based on that, my expectation is that the incident list will contain an array of incidents main data and the Get an incident call would return the full information about the incident. By making a few API calls I confirmed that indeed Get an incident returns slightly more info about some incidents compared to List incident (in my calls it was only the impacted_services array).

However, in the api reference docs, the response schema for both calls is exactly the same. How can I be sure about what is the exact extra data returned by the Get an incident which is not part of the List incidents?

#2

Your expectation is correct – the List Incidents endpoint will list all incidents that meet the criteria you set, while the Get Incident endpoint will get the incident that matches the ID you enter. The Schema is the same because you can ask for all the same data the Get Incident endpoint would include by default in the List Incidents endpoint.

List Incidents

This API returns details about all the Incidents requested for an account. It can apply filters to the request based on a specific date range and/or listing incidents based on their status. This API call is capable of returning multiple incidents in one run.

Get an Incident

This API is more focussed on getting the details of a single incident, this is the reason there is a need to supply the Incident ID in the API call. If you know the Incident ID, then you will use this to fetch a JSON object with details for this one incident. This API call is capable of returning one incident only.

#3

Hi, Thomas. Thanks for the quick response.
If the schema is exactly the same, as you said and as per the documentation, why do I get some extra data about the incident when doing the Get an incident call?

Like, for example, the impacted_services array.

And following up, what other extra data is potentially exposed on the Get an incident that is not in the List incidents endpoint?

#4

This is the way it was designed - you can get all the incidents using the list incidents endpoint and then get more information on an individual incident by putting the incident ID into the GET incident endpoint. I can see how it would be useful to outline that extra information in the response schema, so we have passed that on to the relevant teams here. We are looking into revamping our API docs, so we appreciate the feedback!